feat(api): add ListStageSummaries and WatchStageSummaries RPCs#6159
Draft
jacobboykin wants to merge 4 commits intoakuity:mainfrom
Draft
feat(api): add ListStageSummaries and WatchStageSummaries RPCs#6159jacobboykin wants to merge 4 commits intoakuity:mainfrom
jacobboykin wants to merge 4 commits intoakuity:mainfrom
Conversation
Adds a lightweight Stage projection for list and graph views that need
metadata and current state for many Stages at once but do not need the
full Stage CR. The summary omits FreightHistory entries beyond the
current FreightCollection, PromotionTemplate step configuration, and
Verification configuration. Use GetStage to retrieve the full Stage
resource when detail fields are needed.
Both endpoints are available in ConnectRPC and REST
(GET /v1beta1/projects/{project}/stage-summaries, including
?watch=true for SSE). Requests accept an optional freightOrigins
filter and a resourceVersion for the standard list-then-watch pattern.
Signed-off-by: Jacob Boykin <boykinmusic@gmail.com>
Signed-off-by: Jacob Boykin <jacob.boykin@akuity.io>
✅ Deploy Preview for docs-kargo-io ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #6159 +/- ##
==========================================
+ Coverage 57.56% 57.63% +0.06%
==========================================
Files 474 478 +4
Lines 40469 40741 +272
==========================================
+ Hits 23296 23480 +184
- Misses 15789 15862 +73
- Partials 1384 1399 +15 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Member
Author
|
Some numbers from a local stress test (500 Stages in one project, 10
~6× payload reduction, consistent with the fields the summary omits ( JS heap impact from the browser, measured by fetching +
~6× reduction in JS heap held by the parsed response, tracking the payload reduction linearly.
|
Buf lint enforces lower_snake_case for proto field names. Updated the new StageSummary / ListStageSummaries / WatchStageSummaries messages accordingly. Generated Go struct names (StageSummaries, FreightOrigins, etc.) and protojson wire format (camelCase via the json= tag) are unchanged. Swagger and TypeScript bindings regenerated to match. Signed-off-by: Jacob Boykin <boykinmusic@gmail.com> Signed-off-by: Jacob Boykin <jacob.boykin@akuity.io>
…geSummary
Adds a batch RPC that returns the raw health output blob for a specified
set of Stages in a project, and updates stageToSummary to always leave
Status.Health.Output nil in the summary response. Intended for clients
that use ListStageSummaries for the stage list and want to resolve
per-argocd-app health only for the Stages currently in viewport (React
Flow virtualizes to ~10-30 visible nodes at a time).
The raw health output is typically ~2 KB per Stage and is the single
largest remaining field in StageSummary. Moving it behind a lazy fetch
drops the summary to roughly 1-2 KB per stage, reducing both wire
transfer and the heap footprint of the cached list.
The new endpoint is available in ConnectRPC and REST
(GET /v1beta1/projects/{project}/stage-health-outputs?stageNames=a&stageNames=b).
Stages that do not exist or have no recorded health output are omitted
from the response map; the endpoint has best-effort semantics.
Signed-off-by: Jacob Boykin <boykinmusic@gmail.com>
Signed-off-by: Jacob Boykin <jacob.boykin@akuity.io>
krancour
reviewed
Apr 24, 2026
Comment on lines
+105
to
+119
| // @id ListStageSummaries | ||
| // @Summary List Stage Summaries | ||
| // @Description List a lightweight projection of Stage resources from a | ||
| // @Description project's namespace. Intended for UI list and graph views that | ||
| // @Description need metadata and current state for many Stages at once but do | ||
| // @Description not need full FreightHistory, PromotionTemplate steps, or | ||
| // @Description Verification configuration. Use GetStage for detail fields. | ||
| // @Tags Core, Project-Level | ||
| // @Security BearerAuth | ||
| // @Produce json | ||
| // @Param project path string true "Project name" | ||
| // @Param freightOrigins query []string false "Warehouse name(s) to filter by" collectionFormat(multi) | ||
| // @Success 200 {object} svcv1alpha1.ListStageSummariesResponse | ||
| // @Router /v1beta1/projects/{project}/stage-summaries [get] | ||
| func (s *server) listStageSummaries(c *gin.Context) { |
Member
There was a problem hiding this comment.
Is there a defensible reason for this being a dedicated endpoint instead of just adding an optional summary=true query param to the existing endpoint, in which case, you'll just drop the fields that "summary" excludes?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a lightweight Stage projection for clients rendering list and graph views of many Stages at once. The summary includes Stage metadata and current-state fields but omits heavier fields that are only needed when inspecting a single Stage in detail (full
FreightHistory,PromotionTemplatestep configuration, andVerificationconfiguration). Use the existingGetStageendpoint when detail fields are needed.API
ListStageSummaries(ListStageSummariesRequest)andWatchStageSummaries(WatchStageSummariesRequest)GET /v1beta1/projects/{project}/stage-summaries(supports?watch=truefor SSE)Request options on both list and watch:
freightOrigins(repeated string): restrict results to Stages that request Freight originating from the named Warehouse(s).resourceVersion(string): optional Kubernetes ResourceVersion for the standard list-then-watch pattern.ListStageSummariesreturns the list'sresourceVersionin its response so clients can pass it toWatchStageSummariesand resume from that point.Test plan
stageToSummaryconversion helper (nil, minimal, fully-populated, empty FreightHistory, nil PromotionTemplate, nil Verification, isolation from source mutation).ListStageSummarieshandler includingfreightOriginsfilter cases.make test-unitpasses.make lint-gois clean.